Working With Filters in Widgets

Qrvey provides filtering to refine data based on your needs. When embedding Qrvey Widgets into your system, you may need to combine Qrvey’s filters with your own set of filter controls. This article walks you through the steps needed to pass the values of your own filters to embedded Qrvey widgets. For an general introduction to filters, please see Working with Interactive Filters.

You can pass values to Qrvey’s widgets to filter charts or pages depending on your needs using the Filter Object Structure, as described below. The structure is passed as part of the supported widget’s configuration object as userFilters and it can contain an array of filters with the global scope by default.

The Filter Object

This feature is available with the Dashboard View, Dashboard Builder, Single Panel, and Analytic Suite widgets and you can find sample code in each of the mentioned articles.

var config = {
    attribute1: value1,
    attribute2: value2,
    ...,
    "userFilters": { "filters": [...] }          
  }

Filters Object

Property	Type	Required	Description
operator	String	No	Default AND. Each filter requires a boolean logic to refine the data based on the user’s criteria. Allowed values: AND OR
expressions	Array	Yes	It’s a list of filter criteria to refine the data. Each item in the collection includes one or multiple Expressions Objects.

Expressions Object

Property	Type	Required	Description
qrveyid	String	No	Represent the dataset ID used to refine the data.
questionid	String	No	Represent the dataset’s column ID used to refine the data, should belong to the qrvey defined above.
questionType	String	Yes	It’s only required if the column used to refine the data is a FORMULA or a BUCKET; otherwise, it is optional. Allowed values: FORMULA BUCKET
validationType	String	Yes	The field represents the operand for filtering. Allowed values: EQUAL NOT_EQUAL CONTAIN NOT_CONTAIN END_WITH NOT_END_WITH START_WITH NOT_START_WITH RANGE IS_EMPTY * IS_NOT_EMPTY
property	String	No	When using complex data types like the ones defined inside Webforms, Quizzes, or Surveys, it’s required. Please refer to Complex Properties for a complete list of supported values.
groupValue	String	No	Default ‘day’. Only applies when you want to group date values. Allowed values: year month quarter week day hour minute second
value	Array	Yes	List of values used to filter the data. Qrvey will return all the records that match the criteria defined in the filter. Depending on the column’s data type, you may require additional parameters. Strings "value": [ "United States" ] Number or Date* **lt**: Less than.* **lte**: Less than or equalto.* **gt**: Greater than.* **gte**: Greater than or equal to. "value": [ { "gt": "10507.231" } ] "value": [ { "lte": "11/30/2016", "gte": "05/15/2014" {"}"} ]

Complex Properties

Property	Output	Web Form Column Type
first_name	String	NAME
last_name	String	NAME
full_name	String	NAME
first_name_lower	String	NAME
last_name_lower	String	NAME
full_name_lower	String	NAME
skipped_question	String	NAME, ADDRESS, USADDRESS, LONGTEXT, TEXTFIELD, FILEUPLOAD, IMAGEUPLOAD, DATE, NUMERIC, RATING, SLIDEBAR, YES_NO, DROPDOWN, SINGLE_CHOICE, MULTIPLE_CHOICE, EXPRESSION, CHECKLIST, PASSWORD, EMAIL_FORM, RANKING, SIGNATURE, PHONE, IMAGE, LOOKUP
full_address	String	ADDRESS, USADDRESS
country	String	ADDRESS, USADDRESS
state_code	String	ADDRESS, USADDRESS
state	String	ADDRESS, USADDRESS
country	String	ADDRESS, USADDRESS
state_name	String	ADDRESS, USADDRESS
city	String	ADDRESS, USADDRESS
postal_code	String	ADDRESS, USADDRESS
zip	String	ADDRESS, USADDRESS
address_line_1	String	ADDRESS, USADDRESS
address_line_2	String	ADDRESS, USADDRESS
full_address_lower	String	ADDRESS, USADDRESS
state_code_lower	String	ADDRESS, USADDRESS
state_lower	String	ADDRESS, USADDRESS
state_name_lower	String	ADDRESS, USADDRESS
city_lower	String	ADDRESS, USADDRESS
postal_code_lower	String	ADDRESS, USADDRESS
zip_lower	String	ADDRESS, USADDRESS
address_line_1_lower	String	ADDRESS, USADDRESS
street_address_lower	String	ADDRESS, USADDRESS
address_line_2_lower	String	ADDRESS, USADDRESS
words	String	LONGTEXT o TEXTFIELD, DROPDOWN, LOOKUP
entities	String	LONGTEXT o TEXTFIELD
entitiestype	String	LONGTEXT o TEXTFIELD
sentiment	String	LONGTEXT o TEXTFIELD
keywords	String	LONGTEXT o TEXTFIELD
filesize	Numeric	FILEUPLOAD, IMAGEUPLOAD
filetype	String	FILEUPLOAD, IMAGEUPLOAD
filename	String	FILEUPLOAD
fileurl	String	FILEUPLOAD, IMAGEUPLOAD
all_details	String	FILEUPLOAD, IMAGEUPLOAD
analysis	String	IMAGEUPLOAD
year	Numeric	DATE
month	Numeric	DATE
day	Numeric	DATE
quarter	Numeric	DATE
week	Numeric	DATE
hour	Numeric	DATE
minute	Numeric	DATE
second	Numeric	DATE
value	String	NUMERIC
lower	String	DROPDOWN, SINGLE_CHOICE, MULTIPLE_CHOICE, LOOKUP
expression_type	String	EXPRESSION
local_part	String	EMAIL_FORM
domain	String	EMAIL_FORM
rank{{x}}	String	RANKING. (x) denotes the ranking position.
signature_url	String	SIGNATURE
area_code	String	PHONE
answer_id	String	IMAGE
display_full	String	LOOKUP
display_all	String	LOOKUP
display_{{x}}	String	LOOKUP. Show display with index (x)

Example: A Simple Filter

The following example shows the filter structure for a simple range filter on a numeric column:

Sample Filter: COLUMN_ID BETWEEN 10 AND 15.

...
"userFilters": {
      "filters": [
       {
         "operator": "AND",
         "expressions": [
           {
          "qrveyid": "QRVEY_ID",
             "questionid": "COLUMN_ID",
             "validationType": "RANGE",
             "value": [
               {
                 "lte": 15,
                 "gte": 10
               }
             ]
           }
         ]
       }
     ]
   }

Example: Filter Multiple Columns

The following example shows the filter structure for three filters with different columns and conditions.

Sample Filter:
COLUMN_ID_1 BETWEEN 05/15/2014
AND
11/30/2016
AND
COLUMN_ID_2 EQUAL ‘United States’ AND COLUMN_ID_3 GREATHER_THAN 10507.231

...
 "userFilters": {
     "filters": [
       {
         "operator": "AND",
         "expressions": [
           {
          "qrveyid": "QRVEY_ID",
             "groupValue": "day",
             "questionid": "COLUMN_ID_1",
             "validationType": "RANGE",
             "value": [
               {
                 "lte": "11/30/2016",
                 "gte": "05/15/2014"
               }
             ]
           },
           {
          "qrveyid": "QRVEY_ID",
             "questionid": "COLUMN_ID_2",
             "validationType": "EQUAL",
             "value": ["United States"]
           },
           {
          "qrveyid": "QRVEY_ID",
             "questionid": "COLUMN_ID_3",
             "validationType": "RANGE",
             "value": [
               {
                 "gt": "10507.231"
               }
             ]
           }
         ]
       }
     ]
   }